home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 3 / BBS in a box - Trilogy III.iso / Files / DA / Q-R / ResExpress 1.0.1 ƒ / ResX DevKit / How to write externals < prev    next >
Encoding:
Text File  |  1992-03-03  |  8.0 KB  |  230 lines  |  [TEXT/ttxt]
  1. How to write ResX Externals.
  2.  
  3.  
  4. There are two types of ResX externals:
  5. RXVW (ResX View) 
  6.     -  These are externals that view or edit a SPECIFIC type of resource such
  7.         as an ICON editor or MENU editor.   When installed, it will hilite the
  8.         'View' button when a resource of that type is selected.
  9.  
  10. RXXT (ResX External)
  11.     -  These are externals that can apply to ANY type of resource such as a
  12.         Hex Editor or Resource Duplicator.  Externals also do not have to act
  13.         on a resource.  They could do virtually any function even not related to
  14.         a resource.   A FEdit like external or Data Fork copier are examples.
  15.  
  16. ____________________________________________________________
  17. The following is generalized info for writing externals.  For specific 
  18. instructions, see the RXVW/RXXT Shells and ResX Utils.p.  Detailed guidlines
  19. are provided in the shells.
  20.  
  21.  
  22. Writing 'RXVW's -
  23. When ResX launches a RXVW, it passes a handle of the current selected 
  24. resource to the external code resource.  If several resources are selected,
  25. ResX will pass in the handle one resource at a time.  When writing a 'RXVW',
  26. it is not necessary to handle ALL selected resources, ResX will do that
  27. for you.  Just write the external as if only one resource is selected.
  28.  
  29. The resource is NOT loaded so it is necessary to LoadResource(ResHandle) if needed.  The resource is NOT detached!
  30.  
  31. ResX's global environment is also accessible if needed.  See below.
  32.  
  33.  
  34. Writing 'RXXT's -
  35. These are executed from the 'External' menu.  If a resource is selected, the
  36. handle of the resource is passed in and the same rules apply as for 'RXVW's.
  37.  
  38.  
  39. Global Environment -
  40. SettingsHandle contains Configuration setup, last and second to last files 
  41. opened, and last move info.
  42.  
  43.     SettingsHandle = ^SettingsPtr;                    
  44.      SettingsPtr = ^SettingsRec;        
  45.         SettingsRec = record
  46.                     unused1: Boolean;
  47.                     openStartup: Boolean;                        
  48.                     sortTList, sortRList: Boolean;    
  49.                     lastOneRefNum, lastTwoRefNum: integer;
  50.                     lastOneName, lastTwoName: Str255;
  51.                     lastMoveType: ResType;                    
  52.                     lastMoveID: integer;                        
  53.                     lastMoveSource, lastMoveDest: Str255;    
  54.                     onStartup: integer;        
  55.                     unused2: integer;
  56.                     dClick: integer;                    
  57.                     helpFName: Str255;                        
  58.                 end;
  59.  
  60. unused1: Boolean;
  61.     - Used internally.  Do not alter.
  62.  
  63. openStartup: Boolean;                            
  64.     - If set, the configuration options are enabled from the Configuration.
  65.  
  66. sortTList, sortRList: Boolean;                
  67.     - If sortTlist is set, the Type lists will be sorted alphanumerically.
  68.     - If sortRlist is set, the Resource lists will be sorted alphanumerically.
  69.  
  70. lastOneRefNum, lastTwoRefNum: integer;    
  71.     - Volume reference numbers of the last and second to last files that
  72.        were opened from ResX.
  73.  
  74. lastOneName, lastTwoName: Str255;        
  75.     - File names of last and second to last files that were opened from ResX.
  76.     - This includes the entire path to the file. (Poor Mans Search Path)
  77.  
  78. lastMoveType: ResType;                        
  79.     - Resource type of the last resource that has been copied.
  80.     - This is used in the 'Repeat Last Copy' option.
  81.  
  82. lastMoveID: integer;                            
  83.     - Resource ID of the last resource copied.
  84.     - This is used in the 'Repeat Last Copy' option.
  85.  
  86. lastMoveSource, lastMoveDest: Str255;    
  87.     - Source and Destination Files of the last resource copied.
  88.     - This is used in the 'Repeat Last Copy' option.
  89.  
  90. onStartup: integer;                                
  91.     - Open on startup options. 
  92.     - If equal to 1, the last file is opened.
  93.     - If equal to 2, the last two files are opened.
  94.     - If equal to 3, the open file dialog is opened.
  95.  
  96. unused2: integer;
  97.     - Used internally.  Do not alter.
  98.  
  99. dClick: integer;                                    
  100.     - Current selected item of DoubleClick popup menu.
  101.     - If set to 1, Copy is enabled.
  102.     - If set to 2, Get Info is enabled.
  103.     - If set to 3, View is enabled.
  104.     - If set to 4, Remove is enabled.
  105.  
  106. helpFName: Str255;                            
  107.     - Location of the master Help file.
  108.  
  109. _________________________________________________________
  110.  
  111.  
  112.             GlobalsHndl = ^GlobalsPtr;                            
  113.             GlobalsPtr = ^GlobalsRec;                            
  114.             GlobalsRec = record
  115.  
  116. theDevCtlEnt: DCtlPtr;                            
  117.  - Device Control Entry for the DA.  Do not alter.
  118.  
  119. rsrcBase: Integer;                                
  120.  - Resource Base of the DA.  Do not alter.
  121.  
  122. daMenu: MenuHandle;                            
  123.  - Handle to the DA menu.  This can be altered to be used with an external
  124.     but replace the orginal menu when finished.
  125.  
  126. daFileID: Longint;                                
  127.  - File ID of the DA.  
  128.  
  129. LeftFName, RightFName: Str255;                
  130.  - Path and Name of Left & Right files currently opened. 
  131.  
  132. LeftVNum, RightVNum: integer;                
  133.  - Volume reference numbers  of Left & Right files
  134.  
  135. LWasOpened, RWasOpened: Boolean;            
  136.  - Left/Right file was opened priorly and shouldn't be closed.
  137.  
  138. LcurType, RcurType: ResType;                
  139.  - Current TYPE displayed above resource lists
  140.  
  141. LTcurCell, RTcurCell: Cell;                    
  142.  - Current selected cell in Left/Right TYPE list.
  143.  
  144. LRcurCell, RRcurCell: Cell;                    
  145.  - Current selected cell in Left/Right RESOURCE list
  146.  
  147. LfileID, RfileID: integer;                        
  148.  - Left/Right File IDs.
  149.  
  150. prefsID: integer;                                
  151.  - File ID of ResX Prefs in the System Folder
  152.  - If your external needs to store preferences or hold data, store it in
  153.     this file as a resource.  Use UniqueID() and name the resource the 
  154.     same as your external or view.
  155.  
  156.  
  157. CompactLeft, CompactRight: Boolean;        
  158.  - Left/Right resource map will be compacted when closed if TRUE
  159.  - If a resource is removed for either file, it should be compacted.
  160.  
  161. favMenu, extMenu, openMenu: MenuHandle;    
  162.  - Favorite File/Externals/Open File MenuHandles.  Do not alter.
  163.  
  164. Lopen, Ropen: Boolean;                            
  165.  - True if Left/Right file is open and displayed in ResX
  166.  
  167. MFActive: Boolean;                            
  168.  - True if MultiFinder is running
  169.  
  170. Settings: SettingsHandle;                        
  171.  - Handle to Settings in Configuration setup
  172.  
  173. LTypeList: ListHandle;                        {Handle to Left Type list}
  174. RTypeList: ListHandle;                        {Handle to Right Type list}
  175. LResList: ListHandle;                            {Handle to Left Resource list}
  176. RResList: ListHandle;                            {Handle to Right Resource list}
  177.  
  178.  
  179. Info: ControlHandle;                               {Get Info Button Control Handle}
  180. View: ControlHandle;                           {View Button Control Handle}
  181. OpenLeft: ControlHandle;               {Open Left Button Control Handle}
  182. OpenRight: ControlHandle;              {Open Right Button Control Handle}
  183. Remove: ControlHandle;                     {Remove Button Control Handle}
  184. Copy: ControlHandle;                           {Copy Button Control Handle}
  185.  
  186.  
  187.  
  188. • ResX Utilities -
  189. A toolbox of utilities is included that provide some functions to simplify
  190. writing externals.  It also provides direct access to ResX's Alerts.
  191.  
  192. There are three Alerts inside of ResX.  Pass in a message or question to
  193. these alerts and they will use the Alert resources and routines inside of 
  194. ResX to call the alert.  It is not necessary to include these resources in 
  195. the project.  This simplifies writing externals a great deal and gives a
  196. consistent interface for all externals.
  197.  
  198. • OKAlert(message: Str255);
  199.       Pass in the message to alert the user.  An alert will appear with the
  200.       message with an OK button.
  201.  
  202. • OKCancel(message: Str255): Boolean;
  203.       Pass in the message to alert the user.  An alert will appear with the
  204.       message and OK and Cancel buttons.
  205.       OK returns TRUE, Cancel returns FALSE.
  206.  
  207. • YesNoCancel(question: Str255): integer; 
  208.       Pass in the question to ask the user.  An alert will appear with the
  209.       question and Yes, No, and Cancel buttons.
  210.             Yes returns 1, No returns 0, Cancel returns -1
  211.  
  212.  
  213. The Super Memory Manager-
  214.     This is a combination of the Standard Handle routines and TempHandle
  215.   routines.  Is uses proper Memory Manager calls and is not home made
  216.   handles thus is safe to use.
  217.  
  218.   It's purpose is to provide more memory for externals.  In DA's, externals
  219.   get needed memory from the System Heap.  Unfortunately, when trying
  220.   to create a NewHandle, the SysHeap will not expand into the FreeMem heap.
  221.   SuperHandles uses the FreeMem heap via a TempHandle if there is not
  222.   enough memory in the SysHeap that is requested.  If there is enough 
  223.   memory in the SysHeap, a standard handle is created in that heap.
  224.  
  225.   If a large handle size requested is not available in either heap, it will 
  226.   create a handle at %90 of the available memory in either heap, whichever
  227.   is greater.
  228.  
  229.   See ResX Utils.p or ResX Utils.h for more info.
  230.